---
title: Introduction to Apollo Kotlin
subtitle:  Learn how Apollo Kotlin simplifies GraphQL operations with strongly-typed models, caching, and more
description: Discover Apollo Kotlin, a robust GraphQL client for JVM, Android, and Kotlin multiplatform. Learn its features, setup, and usage to simplify your GraphQL operations.
---

> 📣 **Migration guide:** if you're using Apollo Kotlin 3, see the [migration guide](/kotlin/migration/4.0/). You can also [view the 3.x docs](https://www.apollographql.com/docs/kotlin/v3).

[Apollo Kotlin](https://github.com/apollographql/apollo-kotlin) is a strongly typed GraphQL client that generates Kotlin models for your GraphQL operations.

Apollo Kotlin executes operations against a GraphQL server and returns results as operation-specific Kotlin types. This means you don't have to deal with parsing JSON, or passing around `Map`s and making clients cast values to the right type manually. You also don't have to write model types yourself, because these are generated from the GraphQL definitions your app uses.

Because generated types are operation-specific and validated against the schema, you can only access data that you actually specify as part of an operation. If you don't ask for a particular field in an operation, you can't access the corresponding property on the returned data structure.

This library is designed with Android in mind, but you can use it in any Kotlin application, including KMP ([Kotlin Multi Platform](https://kotlinlang.org/docs/multiplatform.html)).

## Features

* Kotlin Multiplatform code generation
* Queries, Mutations and Subscriptions
* Reflection-free parsing
* Normalized cache
* HTTP cache
* Custom scalar types
* Auto Persisted Queries
* Query batching
* File uploads
* Fake models for tests
* AppSync and graphql-ws websockets
* GraphQL AST parser
* Plugin for Android Studio and IntelliJ

## Getting started

If you are new to GraphQL, check out [the tutorial](https://www.apollographql.com/tutorials/apollo-kotlin-android-part1) that will guide you through building an Android app using Apollo.

If you'd like to add Apollo Kotlin to an existing project, follow the steps below.

Add the plugin to your `build.gradle.kts`:

```kotlin
plugins {
  id("com.apollographql.apollo") version "5.0.0-alpha.3"
}
```

Add the runtime dependency:

```kotlin
dependencies {
  implementation("com.apollographql.apollo:apollo-runtime:5.0.0-alpha.3")
}
```

Set the package name to use for the generated models:

```kotlin
apollo {
  service("service") {
    packageName.set("com.example")
  }
}
```

<Tip>

Using Java? Apollo Kotlin has a dedicated [Java Support](https://apollographql.github.io/apollo-kotlin-java-support/) repository.

</Tip>

Apollo Kotlin supports three types of files:
- `.graphqls` schema files: describes the types in your backend using the GraphQL syntax.
- `.json` schema files: describes the types in your backend using the Json syntax.
- `.graphql` executable files: describes your queries and operations in the GraphQL syntax.

By default, Apollo Kotlin requires a schema in your module's `src/main/graphql` (or `src/commonMain/graphql` for KMP) directory. You can download a schema using introspection using GraphiQL or Studio. Sometimes introspection is disabled, and you will have to ask your backend team to provide a schema. Copy this schema to your module:

```
cp ${schema} ${module}/src/main/graphql/
```

Write a query in a `${module}/src/main/graphql/HeroQuery.graphql` file:

```graphql
query HeroQuery($id: String!) {
  hero(id: $id) {
    id
    name
    appearsIn
  }
}
```

Build your project. This generates a `HeroQuery` class that you can use with an instance of `ApolloClient`:

```kotlin
  // Create a client
  val apolloClient = ApolloClient.Builder()
      .serverUrl("https://example.com/graphql")
      .build()

  // Execute your query. This will suspend until the response is received.
  val response = apolloClient.query(HeroQuery(id = "1")).execute()

  println("Hero.name=${response.data?.hero?.name}")
```

**To learn more about other Apollo Kotlin APIs:**

* Execute your first [mutation](/kotlin/essentials/mutations/).
* Handle [custom scalar types](/kotlin/essentials/custom-scalars/).
* Factor common patterns using [fragments](/kotlin/essentials/fragments/).

## Multiplatform

Apollo Kotlin is a [Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatform.html) project.

Here's the current matrix of supported features per platform:

|                                                      | `jvm` | `Apple¹` | `js` | `wasmJs` | `linuxX64` |
|------------------------------------------------------|:-----:|:--------:|:----:|:--------:|:----------:|
| `apollo-api` (models)                                |   ✅   |    ✅     |  ✅   |    ✅     |     ✅      |
| `apollo-runtime` (network, query batching, apq, ...) |   ✅   |    ✅     |  ✅   |    ✅     |     ✅     |
| `apollo-normalized-cache`                            |   ✅   |    ✅     |  ✅   |    ✅     |     🚫     |
| `apollo-normalized-cache-sqlite`                     |   ✅   |    ✅     |  🚫  |    🚫    |     🚫     |
| `apollo-http-cache`                                  |   ✅   |    🚫    |  🚫  |    🚫    |     🚫     |

¹: Apple currently includes:

- `macosX64`
- `macosArm64`
- `iosArm64`
- `iosX64`
- `iosSimulatorArm64`
- `watchosArm32`
- `watchosArm64`
- `watchosDeviceArm64`
- `watchosSimulatorArm64`
- `tvosArm64`
- `tvosX64`
- `tvosSimulatorArm64`

## Requirements

Some platforms have specific runtime requirements:

* JVM 8+
* Android API level 21+ (`apollo-http-cache` requires enabling [core library desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring) on Android API levels < 26)
* iOS 13+

At build time, it requires:

* Gradle 8.0+
* Kotlin 2.1+ for JVM projects
* Kotlin 2.2+ for native, JS, and Wasm projects

## Proguard / R8 configuration

As the code generated by Apollo Kotlin doesn't use any reflection, it can safely be optimized / obfuscated by Proguard or R8, so no particular exclusions need to be configured.

## Android Studio / IntelliJ plugin

A [plugin for Android Studio and IntelliJ](https://plugins.jetbrains.com/plugin/20645-apollo-graphql) is available to help you work with Apollo Kotlin, providing automatic code generation, integration with the [GraphQL IntelliJ Plugin](https://plugins.jetbrains.com/plugin/8097-js-graphql), navigation to GraphQL definitions, migration helpers, and more.

Installation instructions and more information can be found [here](/kotlin/testing/android-studio-plugin).

## Releases

The latest version is `5.0.0-alpha.3`.

Check the [changelog](https://github.com/apollographql/apollo-kotlin/releases) for the release history.

Releases are hosted on [Maven Central](https://repo1.maven.org/maven2/com/apollographql/apollo/). The plugin is additionally hosted on the [Gradle Plugin Portal](https://plugins.gradle.org/plugin/com.apollographql.apollo)

```kotlin
plugins {
  id("com.apollographql.apollo") version "5.0.0-alpha.3"
}

repositories {
  mavenCentral()
}

dependencies {
  implementation("com.apollographql.apollo:apollo-runtime:5.0.0-alpha.3")

  // Optional: if you want to use the normalized cache
  implementation("com.apollographql.apollo:apollo-normalized-cache-sqlite:5.0.0-alpha.3")
  // Optional: if you just want the generated models and parsers and write your own HTTP code/cache code, you can remove apollo-runtime
  // and use apollo-api instead
  implementation("com.apollographql.apollo:apollo-api:5.0.0-alpha.3")
}
```

## Snapshots

Latest development changes are available in Maven Central's snapshots repository:

```kotlin
// build.gradle.kts
repositories {
  maven {
    url = uri("https://central.sonatype.com/repository/maven-snapshots/")
  }
  mavenCentral()
  // other repositories...
}

// settings.gradle.kts
pluginManagement {
  repositories {
    maven {
      url = uri("https://central.sonatype.com/repository/maven-snapshots/")
    }
    mavenCentral()
    // other repositories...
  }
}
```

The snapshots are updated on each push to `main` and have no retention guarantees. 

Weekly snapshots for the Android Studio / IntelliJ plugin [are also available](/kotlin/testing/android-studio-plugin#weekly-snapshots). 

## Previews

Previews are available in Apollo previews repository:

```kotlin
// build.gradle.kts
repositories {
  maven {
    url = uri("https://storage.googleapis.com/apollo-previews/m2/")
  }
  mavenCentral()
  // other repositories...
}

// settings.gradle.kts
pluginManagement {
  repositories {
    maven {
      url = uri("https://storage.googleapis.com/apollo-previews/m2/")
    }
    mavenCentral()
    // other repositories...
  }
}
```

Previews are published every night 3am UTC time. You can get them by replacing `-SNAPSHOT` with the desired date (e.g. `4.0.2-2024.10.05`). They have 1 year retention.

## Evolution policy

You can read about our evolution policy in the [dedicated page](/kotlin/essentials/evolution)

## Contributing

If you'd like to contribute, please see [CONTRIBUTING.md](https://github.com/apollographql/apollo-kotlin/blob/main/CONTRIBUTING.md).

## Community integrations

* If you're using the [Maven](https://maven.apache.org/) build tool, [apollo-client-maven-plugin](https://github.com/aoudiamoncef/apollo-client-maven-plugin) is a Maven plugin that calls the Apollo Kotlin compiler to generate your Java/Kotlin sources.
* If you're using [Absinthe Phoenix subscriptions](https://hexdocs.pm/absinthe_phoenix/readme.html), [kotlin-phoenix](https://github.com/ajacquierbret/kotlin-phoenix) has a [PhoenixNetworkTransport](https://github.com/ajacquierbret/kotlin-phoenix/blob/main/kotlinphoenix-adapters/src/commonMain/kotlin/io/github/ajacquierbret/kotlinphoenix/adapters/apollo/PhoenixNetworkTransport.kt) that you can use together with `ApolloClient` ([doc](https://github.com/ajacquierbret/kotlin-phoenix/tree/main/kotlinphoenix-adapters))

## Additional resources

- [apollo-kotlin-samples](https://github.com/apollographql/apollo-kotlin-samples) Samples and recipes for advanced features. 
- [Confetti](https://github.com/joreilly/Confetti): A Kotlin Multiplatform conference app using Apollo Kotlin, SwiftUI and Jetpack Compose.
- [MortyComposeKMM](https://github.com/joreilly/MortyComposeKMM): A Kotlin Multiplatform GitHub template using Apollo Kotlin, SwiftUI and Jetpack Compose.
- [A journey to Kotlin multiplatform](https://www.youtube.com/watch?v=GN6LHrqyimI): how the project was moved to Kotlin multiplatform, talk given at Kotliners in June 2020.
- [#125, Fragmented Podcast](http://fragmentedpodcast.com/episodes/125/): Why's and How's about Apollo Kotlin and the entire journey.
- [GraphQL.org](http://graphql.org) for an introduction and reference to GraphQL itself.
- [apollographql.com](http://www.apollographql.com/) to learn about Apollo open-source and commercial tools.
- [The Apollo blog](https://www.apollographql.com/blog/) for long-form articles about GraphQL, feature announcements for Apollo, and guest articles from the community.
- [The Apollo Twitter account](https://twitter.com/apollographql) for in-the-moment news.
